Repository navigation
feat(session): export and restore transcripts, and prewarm - #38
Merged
Merged
Conversation
corasan
force-pushed
the
fm27/transcript
branch
2 times, most recently
from
September 24, 2026 23:15
9311823 to
cb0cda5
Compare
HybridLanguageModelSession now holds its mutable state (session, busy flag, context-reset flag) in one SessionState behind a Synchronization Mutex. The busy check is one check-and-set under the lock, context recovery replaces the session and sets the reset flag in one update, and serializeTranscript and prewarm read the session through the lock. The session is no longer optional, so the sessionNotInitialized guards and the error case are gone. The native instructions-and-transcript guard is gone. The JS constructor is the only entry point and already throws INVALID_SESSION_OPTIONS, so INVALID_TRANSCRIPT now means only that the transcript cannot be decoded. useLanguageModel builds the matching options union member instead of casting. Tests that only restated the mock (transcript forwarding, transcript re-read, prewarm forwarding) are deleted. BREAKING CHANGE: LanguageModelSessionOptions and UseLanguageModelConfig are type aliases for a union of instructions or transcript. An interface that extends either type no longer compiles; use an intersection type.
…thout old summaries A restored session took its base instructions verbatim from the transcript, so each save, restore and overflow cycle appended another summary and recovery kept advertising the tools of the original session. The base is now the caller's instructions with the summary and tool list stripped, recomposed with the tools passed on restore.
corasan
force-pushed
the
fm27/transcript
branch
from
October 16, 2026 23:04
cb0cda5 to
ef7bd52
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A session lives only as long as its JS object. A chat app cannot continue a conversation after a restart. The first request also pays a cold start that the app could hide.
Scope
session.transcriptreturns the conversation as aSerializedTranscript. This is a branded string that holds Apple'sTranscriptJSON fromJSONEncoder. The library does not model Apple's schema. The only promise is that the value restores throughnew LanguageModelSession({ transcript }).LanguageModelSessionOptionsis now a union. A session starts frominstructionsor fromtranscript, not from both. TypeScript rejects both together. At runtime, the JS constructor throwsINVALID_SESSION_OPTIONS. The JS constructor is the only entry point, so native code does not check again. Tools are passed again on restore.useCaseandguardrailsstill apply.LanguageModelSession(model:tools:transcript:).INVALID_TRANSCRIPTmeans only a decode failure. It has a short reason, for examplemissing key 'version'orUnsupported Transcript version: 9.9.session.prewarm(promptPrefix?)forwards toLanguageModelSession.prewarm(promptPrefix:). The SDK method is sync, so the JS method is sync too.useLanguageModelacceptstranscriptin its config. It builds the matching member of the options union, without a cast.HybridLanguageModelSessionkeeps its mutable state (session, busy flag, context-reset flag) in oneSessionStatebehind aSynchronization.Mutex. The busy check is one check-and-set. Recovery replaces the session and sets the reset flag in one update.transcriptandprewarmread the session through the lock. The session is not optional, so thesessionNotInitializederror case is removed.The issue proposed a
transcriptgetter. The native side is a sync method (serializeTranscript()), because Nitro property getters in Swift cannot throw.Latent bug fixed
Context-overflow recovery built the replacement session with the base instructions hard-coded as "You are a helpful assistant". Every session lost its own instructions after an overflow. A restored session has no
config.instructions, so the restore feature would make this worse. The session now keeps its base instructions from init. For a restored session, these come from the transcript's instructions entry.SessionInstructionsowns the instruction format. On restore it strips any earlier summary and the old tool list from the transcript's instructions, then recomposes them with the tools passed on restore. Recovery appends one summary to that base, so summaries do not stack across save, restore and overflow cycles, and recovery never advertises tools the session no longer has.Tradeoffs
stored as SerializedTranscript. The brand stops callers from building a transcript by hand, and it costs one cast at the storage boundary."version":"1.1". It rejects"1.0"and unknown entry roles and segment types. A transcript that holds iOS 27-only content (reasoning entries, attachment segments) is not expected to restore on iOS 26. I did not test on iOS 26, and I do not know which version iOS 26 writes. The docs tell apps to treatINVALID_TRANSCRIPTas a normal result after an OS update.Blast Radius
LanguageModelSessionOptionsandUseLanguageModelConfigchange from interfaces to type aliases. Code thatextendsthem breaks, and must use an intersection type. The CHANGELOG has a BREAKING entry. Code that passes object literals does not change.INVALID_TRANSCRIPT,INVALID_SESSION_OPTIONS,TRANSCRIPT_ENCODING_ERROR.#if compilerguard is needed. All APIs used are iOS 26.Verification
bun run test(75 pass; three tests that only restated the mock are deleted),bun run test:swift(newTranscriptCodingTestsround-trip encode and decode, and invalid JSON,{}, and unsupported version map toINVALID_TRANSCRIPT),typecheck,lint,format:check.A.transcriptand answered "Ana.". A control session with no transcript answered "I don't have access to personal information like your name."'not json','{}'and version9.9each throwAppleAIErrorwith codeINVALID_TRANSCRIPT. Instructions together with a transcript throwINVALID_SESSION_OPTIONS.prewarm()andprewarm('What is')run without an error.CONTEXT_EXCEEDEDandwasContextReset: true.session.transcriptthen read the replacement session, whose instructions are "The secret word is PAPAYA.\n\nPrevious conversation summary: …".Closes #23